Marks (the lite edition)
~~~~~~~~~~~~~~~~~~~~~~~~

So, were you ever reading this huge 300-pages specification heavily
cross-referencing itself, jumping around and getting a headache when looking
for the place where you stopped reading the last time?

Were you doing something similar in C code, but praising *vi* for document
marks?

ELinks can do them, too! For vim non-users:


What it is?
~~~~~~~~~~~

When you place a "document mark" (just mark from now on), you place an
_invisible_ anchor at the current position in the document. You can place
several such marks --- each mark is identified by a single character (any
reasonable character will do). Then, you can just happily browse around
aimlessly (but see below) and when in the same document again, you can return
to any of the marks in the file again. That will restore your position in the
file at the time of placing the mark.

You can place a mark by the "m" key followed by the mark character. You can go
to a mark by the "'" (apostrophe) key followed by the mark character. I.e.  you
can place a mark named "a" in the file by pressing "ma", then returning to it
at any time by typing "'a". You can of course change those shortcuts at any
time to anything you wish in the keybindings manager.


Restrictions
~~~~~~~~~~~~

To make a good start, one non-restriction comes first. The document marks are
local to the document. That means you can have a mark "x" in one document and
another mark "x" in another document and ELinks won't mind and it will get it
right each time.

Now for the restrictions. ALL the document marks are always local to the
document. I.e. the vim text editor has an extension that makes the
capital-letter marks to be global to the whole program and going to such a mark
will make it to open the right document. This is not implemented in ELinks
_yet_.

Contrary to vim, ELinks doesn't support numbered marks (jumping to the last n
documents in history) nor the special "'" mark (jumping to the last mark). Yet.

There is no way to get a listing of all marks set in a document. Yet.


Marks lifespan
~~~~~~~~~~~~~~

I already hinted something about another restriction regarding the aimless
browsing. The lifespan of document marks depends on rather ill-defined and
(for an average mortal) mostly non-deterministic technical conditions.

Generally, marks _always_ survive when not moving away from the document or
when moving only in the session history (and unhistory). That means, if you go
back and the "unback" to the document, you will find your marks safely in
place. If you follow a link from the document (or typed an address to the Goto
URL dialog) and then go back (by pressing the right arrow or through the File
menu), your marks are safe too. These are in fact by far the most common usage
cases for the marks, so most of the time it will just work as you expect.
That's a good news.

The bad news is that in all other cases, nothing is guaranteed. It might work
if you get back to the document by any other means (by following some link or
typing its address to the Goto URL dialog), or it might not. It might be
possible to achieve two instances of the document inside a single ELinks, each
with its own set of marks. However, again, generally it will work as expected -
this paragraph serves only as a disclaimer in cases it doesn't.  Don't rely on
it.

Marks never survive over ELinks restarts. If you quit your ELinks completely
and run it again, the marks you placed will be no more. No exceptions. Well. In
some cases, it *might* appear that they survived, but that just means you did
not quit your ELinks _completely_ --- if you run multiple ELinks instances
under a single user on a single system, they "join" together and you must quit
(or kill) them all to get rid of the damn thing. But that's a different story.



$Id: marks.txt,v 1.3 2004/12/16 13:36:36 jonas Exp $
